home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-01
/
scrnlib.zip
/
SCRNLIB.DOC
< prev
next >
Wrap
Text File
|
1993-01-04
|
37KB
|
1,066 lines
SCRNLIB
By Dave Millis
P.O. Box 2371
Glenview, Illinois 60025
Copyright 1987 by Dave Millis. All rights reserved
2
SCRNLIB release 1
INTRODUCTION
SCRNLIB is a library of text screen routines for the Micro-
soft and Turbo C compilers. Most of the routines were written in
assembly language for the optimum in speed and performance.
These routines remedy some of the deficiencies of C by allowing
screen output in color and allowing for the use of windows.
I was a Turbo Pascal user for two years before I started to
program heavily in C on the PC. In February 1987, I purchased
the Microsoft 'C' Compiler 4.0. I always appreciated the
flexibility and sheer power of C, but I missed the many simple
text output functions of Turbo Pascal. I then decided to write
the functions I needed. After working on this part-time for
several months I collected all the routines into a file called
SCRNLIB.LIB. These routines were tested by several friend and
co-workers who offered some constructive criticism and
suggestions. They even found a couple of bugs. With the
correction of the bugs; the addition of some procedures; and some
minor modifications so the routines will work with both Turbo C
and the Microsoft 'C' Compiler, SCRNLIB release 1 was completed.
I am an active programmer and I have a bachelor's degree in
computer science. I am now primarily using C and assembly and I
generate a multitude of routines that can be beneficial to many
programmers. I am using SCRNLIB to see if there is an interest
in these fast, efficient routines. If there is, later versions
will include more direct memory access screen procedures, more
sophisticated windowing, and many other helpful routines.
By now you might be asking-
DO I NEED SCRNLIB?
Well, I feel SCRNLIB is the best way to output text to the
screen with a color attribute. By "color attribute" I mean the
method that the characters are displayed on the screen. For
monochrome display cards, this means underlined, bold, and
inverse video text. The C programming langauge does not provide
these functions in a nice workable way. One can use ANSI to help
with screen manipulations, however this would require ANSI.SYS be
installed on every machine using these programs and the output
would be slower than if SCRNLIB was used. The SCRNLIB routines
do not require ANSI.SYS be installed and should run on all
systems with standard video hardware (ie. MA, HMA, CGA, EGA)
including most third party video boards. Since these routines
were written in assembly, they run as fast as possible. There is
no doubt that other software producers will develope libraries or
C source code collections that will allow for some of these same
functions; however, If they are not written in assembly, they
Software and Documentation Copyright 1987 by Dave Millis
3
SCRNLIB release 1
will not be as fast as SCRNLIB's routines.
SCRNLIB also allows other input/output operations. For
example, inpstr is a function that enables string inputs from the
keyboard. This function is necessary because the input functions
in standard C does not allow echoing of the input with the
currently set color attribute.
If Windows are desired, SCRNLIB provides a great way to
generate and maintain them.
WINDOWING
SCRNLIB provides for a specified area of the screen to be
the only area written to or effected by many screen operations.
The area, referred to from now on as the active window, is easily
defined and "remembered" by the program. Once defined, the
active window can be cleared, written to, and scrolled up and
down using the normal screen functions provided in SCRNLIB
without effecting the rest of the screen. Output functions, such
as printsh and putsch, continue output at the beginning of the
next line of the active window when the right end of the active
window is encountered. The windows can also be saved and
restored later anywhere on the screen.
Window Example:
Say you want to open a window 30 x 5 characters in size to
display a message and ask for input from the user of your
program. Lets also say you want this window to disappear and
restore the screen to its original condition when you're done
with it. This is what you would do:
1) Save the current screen below where the window will go. This
is done with the scrnsav command:
int x; /*number of char. in the input string*/
char undrwindo[152]; /*define a character string large
enough to save the screen in*/
--> scrnsav(undrwindo,25,10,54,14); /*save portion of screen */
getpos(); /* read current cursor position (into global
variables xposn and yposn */
see the Command section for a full explanation of all commands
2) Next, set the active window:
window(25,10,54,14,0);/*declare active window w/ no border*/
3) To have this window stand out from the rest of the screen, we
Software and Documentation Copyright 1987 by Dave Millis
4
SCRNLIB release 1
will change the foreground and background color attributes:
setattr(1,4); /* blue on red */
cls();
gotoxy(27,12);
This sets the color attribute, clears the 30 x 5 active screen
and positions the cursor over 2 and down 2 form the top left
corner of the window. At this point the screen looks
unchanged except for a 30 x 5 red square in the center.
4) Writing the message is straight forward:
printsh("What is your mother's maiden name? ");
This is not the best way to present this message, but it
illustrates how the windows work. The problem is the message
is longer than the width of the screen. What happens is the
sentence up through "maiden" is printed, then "name? " is
printed on the next line starting at 25,13.
5) Input is handled with the inpstr function:
x=inpstr(mommaname);
6) Finally, now that we have the information we require, we need
to restore the screen to its original condition and position
to its old position:
scrnrst(undrwindo,25,10);
gotoxy(xposn,yposn);
While windows are not an extensively used function in a lot of
programs, the functions in SCRNLIB provides a lot of practical
applications. For example, If you want to generate a program
that actively uses the entire screen except for the 25 row where
the function keys or other information is always displayed, an
active window 80 x 24 can be defined. This way only the top 24
rows will be written to and when the bottom of the active window
is reached the top 24 rows will scroll up, leaving row 25
unchanged.
USING SCRNLIB WITH TURBO-C
When compiling a program in the integrated environment,
SCRNLIBx.LIB must be specified in a project file. For example,
to run DEMO.C with the small memory model, DEMO.PRJ would look
like:
Software and Documentation Copyright 1987 by Dave Millis
5
SCRNLIB release 1
DEMO
\TURBOC\LIB\SCRNLIBS.LIB
(assuming that the SCRNLIBx libraries are in the \TURBOC\LIB
directory)
MORE TECHNICAL INFORMATION
In release 1, all but three of the routines were written in
assembly, using the Microsoft Macro Assembler 4.0. In the
interest of speed and efficiency, the error checking was kept to
a minimum, as is typical of C. It is up to the programmer to
make sure that the proper variables are passed and the proper
amount of memory is allocated for the arrays used. See the
section of commonly made errors for an explanation of the errors
most often made in using SCRNLIB.
In all routines that require an X and Y location, it must be
noted that the top left corner of the screen is 0,0 (not 1,1).
This means the bottom right corner is 79,24.
There are several global variables used by SCRNLIB that are
accessible to the programmer too: oldcurs, scxlow, scxhigh,
scylow, scyhigh, txtattr, xposn and yposn. These keywords should
not be used in other contexts. There exact meanings are as
follows:
oldcurs contains the start and stop scan lines of the cursor
saved with the cursoff function and used by the curson function.
It is uninitialized at the start.
scxlow and scylow define the upper left corner of the active
window. scxhigh and scyhigh define the location of the lower
right corner of the active window. The default values defined in
the header file are: scxlow=0, scylow=0, scxhigh=79, scyhigh=24;
this is just the entire screen. These values can be changed
individually in a program, or through the window command.
txtattr contains the current text color attribute (default
is 07).
xposn and yposn are the current X and Y position of the
cursor set when the function getpos is executed. These
variables, along with the getpos function, exist for the use of
the programmer to easily get the cursor location. xposn and
yposn are only changed by the getpos function and therefore can
be used to store the cursor location.
Software and Documentation Copyright 1987 by Dave Millis
6
SCRNLIB release 1
COMMONLY MADE ERROR WITH SCRNLIB
1) Probably the most common problem results from not declar-
ing string variables large enough to hold all the data put in
them. This over writes other portions of the program and causes
it to crash. This usually occurs with the scrnsav function and
one should carefully read about this function before using it.
2) A stack overflow is a common problem when numerous screen
saves are preformed. This is because many local variables are
stored in the stack area and the screen data strings are very
large. This problem is also not detected using the default
settings in Turbo-C. If your program behaves peculiarly, turn on
the stack overflow checking in the Code generation menu in the
Options-Compiler menu. The easiest way to correct this problem
is to use global arrays (ie. declare the arrays outside of any
functions-this includes function main). If the arrays aren't too
large, you can use the MS link and use the /stack option to
increase the size of the stack. I have not had success using
EXEMOD to increase the size of the stack on Turbo-C (TLINK
linked) files with the stack overflow checking on.
3) Trying to address the last column or the last row of the
screen with 80 or 25 respectively does not work since the bottom
right corner is 79,24. This is because the first column and the
first row are both defined as zero (0).
4) Forgetting to include the SCRNLIB.H file at the beginning
of the program can cause problems.
DISCLAIMER
I do not guarantee that the SCRNLIB functions will do
anything. However, I have tried to write the best, most effi-
cient, and most portable functions that I could, and have tested
them extensively on eight different makes and models of MS-DOS
based microcomputers. I also do not guarantee that SCRNLIB will
not do anything harmful to anything nor anybody. Any discrep-
ancies or problems should be brought to my attention so that I
could improve upon them before the next release. At this time, I
believe SCRNLIB is in perfect working condition. THE USERS OF
SCRNLIB ARE SOLELY RESPONSIBLE ITS EFFECTS IN THEIR CODE.
TRADE MARKS
Turbo Pascal and Turbo C are registered trade marks of Borland
International, Inc.
MS-DOS, MS, Microsoft, and Microsoft 'C' Compiler are a
registered trade mark of Microsoft Corp.
Software and Documentation Copyright 1987 by Dave Millis
7
SCRNLIB release 1
REFERENCE
Even though these routines were written in assembly they
conform to the C calling standard and are used as normal C
procedures and functions. The names have been chosen to describe
the function and so they appear as a natural extension of the C
language.
**************************
beep
PROTOTYPE:
void beep(void);
DESCRIPTION:
I admit this is a very unimpressive procedure to start with,
but I do use it quite often. This routine simply sound the
standard 800 Hz sound for 1/4 seconds.
**************************
cls
PROTOTYPE:
void cls(void);
DESCRIPTION:
This clears the active screen using the current attributes.
**************************
cursoff
PROTOTYPE:
void cursoff(void);
DESCRIPTION:
This turns off the cursor and saves the old cursor type in
the global variable oldcurs. This allows for the old cursor to
be restored. Also allowed is the ability to turn off the cursor
then change to a different form of cursor, using setcurs, then
use curson to restore the original cursor. Remember that cursoff
must be executed before curson will restore the old cursor.
also see: curson,setcurs
Software and Documentation Copyright 1987 by Dave Millis
8
SCRNLIB release 1
**************************
curson
PROTOTYPE:
void curson(void);
DESCRIPTION:
Restore the cursor stored in the global variable oldcurs.
also see: cursoff,setcurs
**************************
getkey
PROTOTYPE:
char getkey(void);
DESCRIPTION:
This get a character from the keyboard.
**************************
getpos
PROTOTYPE:
void getpos(void);
DESCRIPTION:
Gets the current position of the cursor and puts the X and Y
positions in the global variables xposn and yposn respectively.
These two variables, xposn and yposn, are only affected by this
function (and a direct assignment), so they can be used to
reference the position where getpos was last executed.
Software and Documentation Copyright 1987 by Dave Millis
9
SCRNLIB release 1
**************************
gotoxy
PROTOTYPE:
void gotoxy(int xloc,int yloc);
DESCRIPTION:
gotoxy positions the cursor at the screen position defined
by xloc and yloc. The X position and Y position are xloc and
yloc respectively. This function is not limited by the active
screen.
**************************
inpstr
PROTOTYPE:
int inpstr(char *str);
DESCRIPTION:
inpstr gets a string input from the keyboard and echoes the
input on the screen using the current attributes. The string of
input is stored in *str. The returned integer is the number of
characters entered.
**************************
keywait
PROTOTYPE:
char keywait(void);
DESCRIPTION:
keywait clears the keyboard then waits for a single
keystroke from the keyboard. The returned character is the ASCII
value of the first byte of input from the key board. If the key
pressed is a special function key, such as the function keys or
the arrow keys, the return character will be 00h. Since these
special keys input a series of two characters, a character will
remain in the keyboard buffer and the function getkey can be used
to get the second character.
Software and Documentation Copyright 1987 by Dave Millis
10
SCRNLIB release 1
**************************
movxy
PROTOTYPE:
void movxy(int xdis,int ydis);
DESCRIPTION:
This moves the cursor vertically and horizontally from its
current position. xdis and ydis are the displacements from the
current cursor position in the X and Y position respectively.
**************************
printmch
PROTOTYPE:
void printmch(char *chr,int numprn);
DESCRIPTION:
printmch prints a single character a specified number of
times horizontally on the screen using the current attributes.
If the number of characters exceeds the space to the right side
of the screen the remaining characters will rap around the
beginning of the next line. If the printing proceeds to the
bottom right corner of the screen, the screen will not scroll and
the remaining characters will not be printed. This procedure is
not limited by the active screen. *chr is the character to be
printed and numprn is the number of times *chr is to be printed.
This function, along with printmcv, was primarily written to draw
frames and lines on the screen, usually outside the active
screen.
printmch, along with all the printing routines, uses the
BIOS to output to the screen. In future releases, there will be
the option of doing output using the BIOS or direct memory
access. There will be a global variable that will dictate which
method is to be used. This variable can be changed in the
program, so a command line option can be added to your programs
to set the output method.
also see: printmcv
Software and Documentation Copyright 1987 by Dave Millis
11
SCRNLIB release 1
**************************
printmcv
PROTOTYPE:
void printmcv(char *chr, int numprn);
DESCRIPTION:
printmcv prints a single character a specified number of
times vertically on the screen using the current attributes. If
the number of characters exceeds the space to the down the rest
of the screen, the remaining characters are not printed. *chr is
the character to be printed and numprn is the number of times
*chr is to be printed. This procedure is not limited by the
active screen. This function, along with printmch, was primarily
written to draw frames and lines on the screen, usually outside
the active screen.
also see:printmcv
**************************
printsh
PROTOTYPE:
void printsh(char *str);
DESCRIPTION:
printsh prints a string horizontally in the active window
using the current attributes. If the end of the active window is
reached, the string continues on the next line of the active
window. If the end of the active window is reached the window
will scroll up and the rest of the string will be printed. All
of the back slash (\) functions are supported as they are in the
standard C printf procedure; however, the % functions for
printing numbers and other strings are not supported yet. To
generate output in the same fashion as printf the sprintf
function can be used alone with printsh:
sprintf(txt,"a=%d b=%d",a,b);
printsh(txt);
Remember to include stdio.h when using sprintf.
Support for numbers and additional strings is currently one
of my primary projects.
also see printsv,putsch
Software and Documentation Copyright 1987 by Dave Millis
12
SCRNLIB release 1
**************************
printsv
PROTOTYPE:
void printsv(char *str);
DESCRIPTION:
printsv prints the given string vertically in the active
screen using the current attributes. If there is not a enough
space from the current cursor position to the bottom of the
window the remainder of the string is truncated. The only back
slash commands supported are the \a and \b. Like the printsh
routine, the % format specifications are not supported, yet.
also see printsh,putsch
**************************
putsch
PROTOTYPE:
void putsch(char *chr);
DESCRIPTION:
putsch prints a single character at the cursor position with
the current attribute. This function only works in the active
window and advances to the next line of the active window after
printing a character in the last active column. All the back
slash commands are supported.
also see printsh,printsv
**************************
scrldn
PROTOTYPE:
void scrldn(int);
DESCRIPTION:
scrldn scrolls the active screen down the number of rows
specified by int. The current background attribute is used for
the blank lines added to the top of the screen as the screen
scrolls.
also see scrlup
Software and Documentation Copyright 1987 by Dave Millis
13
SCRNLIB release 1
**************************
scrlup
PROTOTYPE:
void scrlup(int);
DESCRIPTION:
scrlup scrolls the active screen up the number of rows
specified by int. The current background attribute is used for
the blank lines added to the bottom of the screen.
also see scrldn
**************************
scrnoff
PROTOTYPE:
void scrnoff();
DESCRIPTION:
scrnoff blanks the screen.
also see scrnon
**************************
scrnon
PROTOTYPE:
void scrnon();
DESCRIPTION:
scrnon turns the screen back on after a scrnoff has been
executed.
also see scrnoff
Software and Documentation Copyright 1987 by Dave Millis
14
SCRNLIB release 1
**************************
scrnrst
PROTOTYPE:
void scrnrst(char *str,int xl,int yl);
DESCRIPTION:
scrnrst restores a saved screen that was saved with scrnsav
or scrnsavd. str is the character array that stores the screen
information, xl and yl makeup the x and y position of the top
left corner of where the window is to be restored.
scrnrst(d) can also be used with scrnsav(d) to move windows.
A window or an area of the screen can be saved and then restored
at a different location by specifying a different xl and yl in
the restore cammand. The dimensions of the screen remain the
same as they are stored in the data string.
also see scrnrstd,scrnsav,scrnsavd
**************************
scrnrstd
PROTOTYPE:
void scrnrstd(char *str,int xl,int yl);
DESCRIPTION:
scrnrstd works exactly like scrnrst. The only difference is
that scrnrstd uses direct memory access to restore the screen.
This provides a great speed enhancement over scrnrst, which uses
the BIOS, but it may not be as portable to other computers.
also see scrnrst,scrnsav,scrnsavd
Software and Documentation Copyright 1987 by Dave Millis
15
SCRNLIB release 1
**************************
scrnsav
PROTOTYPE:
void scrnsav(chr *str,int xl,int yl,int xh,int yh);
DESCRIPTION:
scrnsav saves a rectangular portion of the screen. The
information from this portion of the screen is stored in the
character string str. xl and yl define the upper left corner and
xh and yh define the lower right corner of the rectangle.
Calculation to determine the size of *str:
size = (2 x (xh - xl + 1) x (yh - yl + 1)) + 2)
This is simply the size of the window times 2, plus 2. The
reason for this is 2 bytes must be stored for each character on
the screen, one for the character and one for the attribute, then
the first 2 bytes of the string contain the size of the array
(more specifically the X size and Y size).
It is VERY important that *str is large enough to hold all
the data. Unpredictable results will occur if this space is too
small. It does not make any difference if this space is too
large.
also see scrnrst,scrnrst,scrnsavd
**************************
scrnsavd
PROTOTYPE:
void scrnsavd(chr *str,int xl,int yl,int xh,int yh);
DESCRIPTION:
scrnsavd works exactly like scrnsav. The only difference is
that scrnsavd uses direct memory access to save the screen. This
provides a great speed enhancement over scrnsav, which uses the
BIOS, but it may not be as portable to other computers.
also see scrnrst,scrnrstd,scrnsav
Software and Documentation Copyright 1987 by Dave Millis
16
SCRNLIB release 1
**************************
setattr
PROTOTYPE:
void setattr(int fgrnd,int bgrnd);
DESCRIPTION:
setattr sets the current color attribute to be used for the
screen output functions. fgrnd is an integer from 0-15 that
specfies the foreground color. These numbers correspond to:
0 - Black 8 - Gray
1 - Blue (underline) 9 - Bright Blue (bright underline)
2 - Green 10 - Bright Green
3 - Cyan 11 - Bright Cyan
4 - Red 12 - Bright Red
5 - Magenta 13 - Bright Magenta
6 - Brown 14 - Yellow or Bright Brown
7 - White 15 - Bright White
The descriptions in parentheses are for monochrome cards.
bgrnd is an integer also from 0-15 where 0-7 specifies the
background color. 0-7 correspond to the same colors as the
foreground colors above. 8-15 correspond to a the same
background color as 0-7 respectively, but causes the foreground
color to blink.
**************************
setcurs
PROTOTYPE:
void setcurs(int curstrt, int curstop);
DESCRIPTION:
setcurs set the cursor type. curstrt is the first scan line
and curstop is the final scan line that makes up the cursor.
The cursor is defined by the number and positions of lines
that make it up. For example, the cursor on a CGA is made up of
lines 6 and 7 (curstrt=6, curstop=7). A box cursor on a CGA
would be: curstrt=0, curstop=7. The total number of line on a
monochrome is 14 (0-13). If curstrt is larger than curstop, the
scan lines will wrap around and the cursor will appear as two
sets of lines.
also see cursoff,curson
Software and Documentation Copyright 1987 by Dave Millis
17
SCRNLIB release 1
**************************
window
PROTOTYPE:
void window(int xl,xin yl,int xh,int yh,int brdrtype);
DESCRIPTION:
window sets the active window. xl and yl define the top
left corner and xh and yh are the lower right corner of the
window. brdrtype is the type of border that will be drawn around
the window: 0 is no border, 1 is a single line boarder, and 2 is
a double line border. This border is drawn OUTSIDE of the active
screen. This means that if a border is specified, the total
boundaries of the screen will be: xl-1,yl-1,xh+1,yh+1. One word
of warning, do not try and draw a border around a window that has
an edge of the ACTIVE screen as one of its borders. This will
usually cause the border to be printed at the other edge of the
screen (It wraps around).
Software and Documentation Copyright 1987 by Dave Millis
18
SCRNLIB release 1
REGISTRATION
I wrote SCRNLIB with the purpose of making programming a
little bit easier and a little bit more fun. With this in mind,
I would like to encourage everyone who uses SCRNLIB to freely
copy it and upload it to other bulletin boards providing that: 1)
No fee is charged for such copying and distribution and 2)
SCRNLIB is distributed ONLY in its ORIGINAL form, unmodified in
anyway.
I do ask, however, that those who find SCRNLIB useful become
registered users and obtain a license for its use. Only
registered users may use SCRNLIB in the development of their own
programs and may sell or distribute these programs to others.
Registered users will also receive technical support and will be
informed of any major developments and improvements.
To register, just send $10 along with the attached
registration form and in return I will mail you : 1) the Latest
Version of SCRNLIB including libraries that work with each of the
Small, Medium, Compact, and Large memory modules. 2) The Latest
Documentation.
If you try SCRNLIB and feel it's not quite for you, please
still send us your opinion of the product and any suggestions. I
welcome and encourage any input anyone has.
________________________________________________________________
cut along dashed line and mail with check for $10 per license
and $1 postage and shipping for each disk requested to DAVE
MILLIS PO BOX 2371, GLENVIEW, ILLINOIS 60025
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
I HAVE ENCLOSED $_______ FOR _____ COPIES OF SCRNLIB TO BE
REGISTERED TO:
NAME_______________________________
COMPANY____________________________
ADDRESS________________________________________________________
CITY_______________________________
STATE__________ ZIP CODE____________
PHONE ( )______________________ ( )_______________________
CURRENT RELEASE IN YOUR POSSESSION _________
___ PLEASE CONTACT ME ABOUT QUANTITY PRICING OR SITE LICENSING.
Copyright 1987 by Dave Millis. All rights reserved.
19
SCRNLIB release 1
FUTURE RELEASES
All the printing routines use the BIOS to output to the
screen. In future releases, there will be the option of doing
output using the BIOS or direct memory access. There will be a
global variable that will dictate which method is to be used.
This variable can be changed in the program, so a command line
option can be added to your programs to set the output method.
I currently have several more functions that I have not
tested thoroughly enough yet to include with this release. They
include functions that: set the border color; check and set the
video mode (SCRNLIB functions work in 40 character mode also);
allow for a max number of characters to be input with the string
input function; support more sophisticated windowing; ... and
many more.
Copyright 1987 by Dave Millis. All rights reserved.